/*
 * Copyright (c) 2003-2004, Inversoft, All Rights Reserved
 *
 * This software is distribuable under the GNU Lesser General Public License.
 * For more information visit gnu.org.
 */
package org.emergent.antbite.savant;


import java.io.File;
import java.net.URL;


/**
 * <p>
 * This interface describes the method by which URLs are
 * constructred for artifacts. Given an artifact, an
 * implementation of this class will generate a URL that
 * can be contacted to attempt to retrieve the artifact.
 * </p>
 *
 * @author Brian Pontarelli
 */
public interface URLBuilder {

    /**
     * Attempts to builds a URL for the given artifact.
     *
     * @param   artifact The artifact to build the URL for
     * @param   defaultDomain The default domain URL specification (base URL)
     * @param   mapping A Mapping file that can be used to map groups to base URLs
     *          to override the default
     * @return  The URL or null if one could not be built
     */
    URL buildURL(String defaultDomain, File mapping, Artifact artifact)
    throws SavantException;

    /**
     * Attempts to builds a URL to the MD5 hash for the given artifact.
     *
     * @param   artifact The artifact to build the URL for
     * @param   defaultDomain The default domain URL specification (base URL)
     * @param   mapping A Mapping file that can be used to map groups to base URLs
     *          to override the default
     * @return  The MD5 URL or null if one could not be built
     */
    URL buildMD5URL(String defaultDomain, File mapping, Artifact artifact)
    throws SavantException;

    /**
     * Attempts to builds a URL to the XML dependency meta-data for the given
     * artifact.
     *
     * @param   artifact The artifact to build the URL for
     * @param   defaultDomain The default domain URL specification (base URL)
     * @param   mapping A Mapping file that can be used to map groups to base URLs
     *          to override the default
     * @return  The XML dependency URL or null if one could not be built
     */
    URL buildDepsURL(String defaultDomain, File mapping, Artifact artifact)
    throws SavantException;
}